Apache Wink : JAX-RS HTTP Headers

HTTP headers generally store metadata and control information. There are some common headers shared in requests and responses but there are a few specific headers to either a request or a response. Developers should read the HTTP specification for a complete understanding of HTTP headers. Some of the more common HTTP headers are mentioned below in cases where JAX-RS provides convenient methods for the header.

Generally, in order to get the request header name and values, developers can use either an injected @HeaderParam annotated with a parameter/field/property or an injected @Context HttpHeaders parameter/field/property.

@Path("/example")
public ExampleResource {
    @Context HttpHeaders requestHeaders;

    @GET
    public void getSomething(@HeaderParam("User-Agent") String theUserAgent) {
        /* use theUserAgent variable or requestHeader's methods to get more info */
    }
}

In order to set response headers, developers can set them on a javax.ws.rs.core.Response return object.

@Path("/example")
public ExampleResource {
    @GET
    public Response getSomething() {
        return Response.ok(/* some entity */).header("CustomHeader", "CustomValue").build();
    }
}

A response headers can be set when a MessageBodyWriter#writeTo() method is called.

Common Headers

The common header specifies the size and type of a header. Every header must begin with the common header. The common header must not appear by itself.

Content-Type

The Content-Type signals the media type of the request/response entity. The Content-Type header on requests is read via HttpHeaders#getMediaType() method. The Content-Type is set for responses when doing a javax.ws.rs.core.Response.ResponseBuilder#type() method or a javax.ws.rs.core.Response.ResponseBuilder#variant() method.

Content-Language

The Content-Language denotes what language the entity is in. In order to receive the request entity language, use the HttpHeaders#getLanguage() method. In order to set the response entity language, use the javax.ws.rs.core.Response.ResponseBuilder#language() method.

Content-Length

The Content-Length is useful for determining the entity's length. If possible, the MessageBodyWriter entity providers will automatically set the Content-Length if possible, and some containers will set the response Content-Length if the entity is small.

Reference
Refer to the HTTP spec for more details on when this header is set and valid.

Common Request HTTP Headers

An HTTP Request Header is a line of text that a client software (i.e. Web Browser) sends to a server together with other request data.

The Accept header is used to determine the possible response representations that the client prefers such as XML over JSON but not plain text. When a resource method is effectively annotated with a @Produces, any incoming request must have a compatible Accept header value for the resource method to be selected. Clients can set quality parameters (priority ordering) for the best possible response and services generally try to honor the request. To get the best representation of a response, use either the HttpHeaders#getAcceptableMediaTypes() or Request#selectVariant() methods.

Accept-Language

Like the Accept header, Accept-Language lists the preferred languages. A HttpHeaders#getAcceptableLanguages() method will list the acceptable languages in a preferred order.

If-Match and If-None-Match

If a previous response had an ETag header, the client can re-use the ETag value with the If-Match or If-None-Match request header to do conditional requests (if the server application supported the If-Match/If-None-Match headers). For example, a POST with an If-Match header and an old ETag value should only execute the POST request if the old ETag value is still valid. javax.ws.rs.core.Request#evaluatePreconditions() may help evaluate the If-Match and If-None-Match headers.

If-Modified-Since and If-Unmodified-Since

Like ETags, If-Modified-Since and If-Unmodified-Since are based on the Last-Modified date. Using either request header with a date, will set up a conditional request (if the server application supports the headers). For instance, a GET with an If-Modified-Since header of an old known date would allow the server to send back a response with just a HTTP status code of 304 (Not Modified). By sending back a HTTP status code of 304, the server is telling the client that the resource has not changed so there is no need to re-download the resource representation. This could save precious bandwidth for the client. javax.ws.rs.core.Request#evaluatePreconditions() may help evaluate the If-Modified-Since and If-Unmodified-Since headers.

Important Note
Note that date formats are specified in the HTTP specification.

Common Response HTTP Headers

HTTP Headers form the core of an HTTP request, and are very important in an HTTP response. They define various characteristics of the data that is requested or the data that has been provided. The headers are separated from the request or response body by a blank line

ETag

ETags or entity tags can be set. Like a hashcode, it is given to the client so a client can use various control request headers such as If-Match and If-None-Match for conditional requests. javax.ws.rs.core.Response.ResponseBuilder#tag() and javax.ws.rs.core.EntityTag are useful for ETags.

Expires

The Expires response header indicates the amount of time that the response entity should be cached. It is useful to set the expiration for data that is not going to change for a known time length. Browsers use this response header to manage their caches among other user agents.The javax.ws.rs.core.Response.ResponseBuilder#expires() method can be used to set the Expires header.

Last-Modified

Last-Modified specifies the date when the resource was changed. A client can use the response value in combination with If-Modified-Since and If-Unmodified-Since request headers to perform conditional requests.The javax.ws.rs.core.Response.ResponseBuilder#lastModified() method can be used to set the Last-Modified header.

Important Note
Note that date formats are specified in the HTTP specification.

Location

The Location response header usually indicates where the resource is located (in a redirect) or the URI of the new resource (when resources are created and usually in a HTTP 201 response). The javax.ws.rs.core.Response.ResponseBuilder#location()method can be used to set the Location header.